/** @file
@brief The core Pryn Library.

This header file includes the core Pryn library, which includes everything related to creating and manipulating components. On Windows, this library is pryn.dll; on Posix, this library is pryn.so. If you want to graphically edit a Pryn component network or graphically change Pryn settings, then look to @link prynEditor.h prynEditor.h @endlink.

The core object of Pryn is the #PrynState, which holds information about all other structures and is used as a source for allocation functions. There are a few different ways to do this, depending upon how much control you require. First here's the process with the least control:

@code
PrynState *state; // Will hold the state object.
PrynResult result; // Error code in C.

// In C:
if ((result = prynCreateState (&state)) < 0)
	// An error occurred.

// In C++:
state = PrynState::Create ();

// In most other object-oriented languages:
state = new PrynState ();
@endcode

If you need to use your own memory allocation functions, then you'll call this instead:

@code
void *allocate (PrynState *state, uintptr_t length) { } // Allocate a number of bytes.
void free (PrynState *state, void *data) { } // Free some previously allocated data.
void *platform; // Data passed to the allocation and free functions.

// In C:
if ((result = prynCreateStateWithAllocator (&state, &allocate, &free, platform)) < 0)
	// An error occcurred.

// In C++; most other languages won't support this:
state = PrynState::Create (&allocate, &free, platform);
@endcode

Initially there's nothing within the state - no factories, no types, nothing. These come from external libraries. The typical process is to use a configuration. You can use the user-global configuration or a local one, or a combination thereof.

To be continued...

@page language-differences Language Differences

Pryn has support for various languages but uses unified documentation to minimise development issues like documentation lag. This page describes support for each language, and tells you how to read the documentation for it.

@section C

Pryn is implemented in C, so the C API is the lowest-level binding to the library. It is not, however, recommended; doing anything in C requires lots of code to do at all, and plenty more to do properly (detecting and recovering from errors). The bright side is that the API itself is secure, so you can actually ignore any error without having the program destroy itself as a result, although you will not be able to determine exactly when the program goes wrong. The only way to confuse the API would be to hand it uninitialised pointers.

For any code outside of Pryn itself, however, it's strongly recommended to use C++ as the absolute minimum binding language.

Documentation for C can generally be read plainly; just ignore any member functions as those are C++-based. Functions and types relevant to one major type are grouped into their own modules, which you can see listed under Modules to the left, or you can click on the link at the top of a page for a type.

@section Cpp C++

A major difference between using C versus using C++ is that C uses PrynResult to return error codes and fields within the state for any additional data, while C++ throws #PrynException. Ordinarily exceptions are automatically thrown when using the C++ API, but if you call any function which returns #PrynResult an exception cannot be thrown. Use the @e checkError method present in every class in that case to throw an exception if an error code is returned.

The flip side where you might throw a #PrynException in a callback and want it to be caught and transformed into a #PrynResult is generally not necessary, because callbacks are wrapped such that this is done automatically. However it can be simply done by catching #PrynException and returning its @e result field.

To read the documentation for C++, look at the member functions inside structures and ignore global functions. All global functions have member functions wrapping them, so you never need to call a global function directly.

For implementing types and factories, you can alternately use the #PrynTypeClass and #PrynFactoryClass facilities. These allow you to implement them as classes using virtual member functions in a very C++-like manner.

*/
#ifndef PRYN_H
#define PRYN_H

#include <pryn/common.h>
#include <pryn/component.h>
#include <pryn/factory.h>
#include <pryn/library.h>
#include <pryn/mediator.h>
#include <pryn/monitor.h>
#include <pryn/object.h>
#include <pryn/pin.h>
#include <pryn/platform.h>
#include <pryn/result.h>
#include <pryn/state.h>
#include <pryn/stream.h>
#include <pryn/string.h>
#include <pryn/tag.h>
#include <pryn/type.h>
#include <pryn/utility.h>
#include <pryn/value.h>
#include <pryn/vector.h>

#include <pryn/cpp.h> // Note: This must be last.

#endif /* PRYN_H */
